home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / xlib04.zip / XLIBREF2.DOC < prev    next >
Text File  |  1992-11-10  |  26KB  |  767 lines
  1. PART 2 of 2
  2. -----------------------------------------------------------------------------
  3.  
  4.   *********      XLIB - Mode X graphics library           ****************
  5.   *********                                               ****************
  6.   ********* Written By Themie Gouthas                     ****************
  7.   *********                                               ****************
  8.   ********* egg@dstos3.dsto.gov.au                        ****************
  9.   ********* teg@bart.dsto.gov.au                          ****************
  10.  
  11.       Some of the code in this library has been contributed by :
  12.  
  13.                Matthew MacKenzie - matm@eng.umd.edu
  14.  
  15.   Notes:
  16.     References to my employer have been removed as this library is my
  17.     own intellectual property, developed solely in my own time.
  18.  
  19.     I informally reserve all rights to the code in XLIB.
  20. -----------------------------------------------------------------------------
  21.  
  22. --------------------------------------------------------------------------
  23. MODULE  XCLIPPBM   note: VERY SIMILAR to XPBMCLIP
  24.            This module implements clipping pbm puts that are pixel
  25.            alignment independent  (and thus a little slower)
  26. --------------------------------------------------------------------------
  27.                  XCLIPPBM:
  28.                  Blits and Pieces
  29.                by Matthew MacKenzie
  30.  
  31. The XCLIPPBM module contains clipping versions of two of the three routines
  32. in the XPBITMAP module:
  33.   o  x_clip_pbm transfers a planar bitmap to the screen, clipping off any
  34.      part outside a bounding box.
  35.   o  x_clip_masked_pbm does the same thing, but transfers only nonzero
  36.      pixels.
  37.  
  38.     The planar bitmap format is described elsewhere.  Here we will look at
  39. the clipping itself, since it is the only distinguishing feature of this
  40. module.
  41.     The bounding box is made up of four integers, TopBound, BottomBound,
  42. LeftBound, and RightBound.  Unlike most global variables in Xlib, these are
  43. meant to be written to.  In fact, they start out uninitialized.  Be sure to
  44. set them before you try plotting any clipped bitmaps.
  45.     Note that these are not the same variables which are used in the other
  46. clipping modules in Xlib.  This is because the two systems are incompatible:
  47. the other modules clip horizontally to columns while this one clips to
  48. pixels.  As you might have guessed, those functions and these were developed
  49. in different hemispheres of the planet...
  50.     If it's any consolation, this does give you two independent
  51. bounding boxes to futz with, should the mood visit you.
  52.     Bitmaps cannot go outside the perimeter of the bounding box, but they
  53. can overlap it.  If TopBound equals BottomBound, for example, a horizontal
  54. slice of a bitmap may still be plotted.  It is safe to turn the box "inside
  55. out" to make sure nothing will be plotted -- this is the first thing each
  56. routine checks for.
  57.     To plot a bitmap, minus its zero pixels, minus anything outside the
  58. bounding box:
  59.  
  60. x_clip_masked_pbm (int X, int Y, int ScreenOffs, char far * Bitmap);
  61.  
  62.     The arguments are in the same order as those for x_put_masked_pbm in
  63. the module XPBITMAP.  The bounding box is relative to the given
  64. ScreenOffs(et).  This lets you perform page flipping without worrying about
  65. what screen you are clipping to -- it's always the current screen.  The
  66. bitmap itself, of course, is not affected; clipping is performed on-the-
  67. fly.
  68.     The third function in XPBITMAP, for which this module has no
  69. equivalent, copies from video RAM to system RAM.  The absence of such a
  70. routine may seem at first like a disadvantage -- but this, like so many
  71. things in this life, is an illusion.  You can use the unclipped routine,
  72. and clip the bitmap when you want to plot it back onto the screen.
  73.  
  74.   ASM SOURCES
  75.  
  76.      xclippbm.asm xclippbm.inc xlib.inc model.inc
  77.  
  78.   C HEADER FILE
  79.  
  80.      xclippbm.h
  81.  
  82.   EXPORTED VARIABLES
  83.  
  84.   TopBound - int
  85.   BottomBound - int
  86.   LeftBound - int
  87.   RightBound -int
  88.  
  89.   EXPORTED FUNCTIONS
  90.  
  91.   x_clip_pbm
  92.   ----------
  93.   C Prototype: extern void x_clip_pbm (int X, int Y, int ScreenOffs, char
  94.                                        far * Bitmap);
  95.  
  96.   Copies a planar bitmap from SRAM to VRAM, with clipping */
  97.  
  98.   x_clip_masked_pbm
  99.   -----------------
  100.   C Prototype: extern void x_clip_masked_pbm (int X, int Y,
  101.                                    int ScreenOffs, char far * Bitmap);
  102.  
  103.   Copies a planar bitmap from SRAM to VRAM, with clipping -- 0 bytes
  104.   in the bitmap are not copied.
  105.  
  106.  
  107.  
  108. --------------------------------------------------------------------------
  109. MODULE  XMOUSE
  110. --------------------------------------------------------------------------
  111. The XMOUSE module implements very basic mouse handling functions. The way
  112. in which it operates is by installing an event handler function during
  113. initialization which subsequently intercepts and processes mouse events and
  114. automatically updates status variables such as mouse position and button
  115. pressed status. It does not support the full functionality of:
  116.  
  117.   SPLIT SCREENS
  118.   SCROLLED WINDOWS
  119.   VIRTUAL WINDOWS
  120.  
  121. This was done to primarily prevent unecessary impedences to performance,
  122. since the mouse handler function has the potential to degrade performance.
  123. It also saves me alot of coding which I was too lazy to do.
  124.  
  125. Programs communicate with the mouse driver as with other devices, through
  126. an interrupt vector namely 33h. On generating an interrupt, the mouse driver
  127. expects a function number in AX and possibly other parameters in other
  128. registers and returns information via the registers. A brief description
  129. of the mouse functions follows:
  130.  
  131.           --------------------------------------
  132.  
  133.           MS Mouse Driver Functions
  134.  
  135.           Mouse Initialization                 0
  136.           Show Cursor                          1
  137.           Hide Cursor                          2
  138.           Get Mouse Position & Button Status   3
  139.           Set Mouse Cursor Position            4
  140.           Get Button Press Information         5
  141.           Get Button Release Information       6
  142.           Set Min/Max Horizontal Position      7
  143.           Set Min/Max Vertical Position        8
  144.           Define Graphics Cursor Block         9
  145.           Define Text Cursor                  10
  146.           Read Mouse Motion Counters          11
  147.           Define Event Handler                12
  148.           Light Pen Emulation Mode ON         13
  149.           Light Pen Emulation Mode OFF        14
  150.           Set Mouse Mickey/Pixel Ratio        15
  151.           Conditional Hide Cursor             16
  152.           Set Double-Speed Threshold          19
  153.           --------------------------------------
  154.  
  155. In practice only afew of these functions are used and even fewer when the
  156. mouse status is monitored by an event handler function such as is used in
  157. this module.
  158.  
  159. The most important thing to note when using the mouse module is that the
  160. mouse event handler must be removed before exiting the program. It is a good
  161. idea to have an exit function (see the C "atexit" function) and include the
  162. line "x_mouse_remove();" along with any other pre-exit cleanup code.
  163.  
  164. See also: XDETECT for mouse detection.
  165.  
  166.   ASM SOURCES
  167.  
  168.     xmouse.asm xlib.inc model.inc
  169.  
  170.   C HEADER FILE
  171.  
  172.     xmouse.h
  173.  
  174.   EXPORTED VARIABLES
  175.  
  176.    MouseInstalled    - WORD - Indicates whether mouse handler installed
  177.    MouseHidden       - WORD - Indicates whether mouse cursor is hidden
  178.    MouseButtonStatus - WORD - Holds the mouse button status
  179.    MouseX            - WORD - Current X position of mouse cursor
  180.    MouseY            - WORD - Current Y position of mouse cursor
  181.    MouseFrozen       - WORD - Disallows position updates if TRUE
  182.    MouseColor        - BYTE - The mouse cursors colour
  183.  
  184.   EXPORTED FUNCTIONS
  185.  
  186.   x_mouse_init
  187.   ------------
  188.  
  189.     C Prototype:  int x_mouse_init()
  190.  
  191.   Initialize the mouse driver functions and install the mouse event handler
  192.   function. This is the first function you must call before using any of the
  193.   mouse functions. This mouse code uses the fastest possible techniques to
  194.   save and restore mouse backgrounds and to draw the mouse cursor.
  195.  
  196.   WARNING: This function uses and updates "NonVisual_Offset" to allocate
  197.        video ram for the saved mouse background.
  198.  
  199.   LIMITATIONS: No clipping is supported horizontally for the mouse cursor
  200.            No validity checking is performed for NonVisual_Offs
  201.  
  202.   **WARNING** You must Hide or at least Freeze the mouse cursor while drawing
  203.           using any of the other XLIB modules since the mouse handler may
  204.           modify vga register settings at any time. VGA register settings
  205.           are not preserved which will result in unpredictable drawing
  206.           behavior. If you know the drawing will occur away from the
  207.           mouse cursor set MouseFrozen to TRUE (1), do your drawing
  208.           then set it to FALSE (0). Alternatively call "x_hide_mouse",
  209.           perform your drawing and then call "x_show_mouse". Another
  210.           alternative is to disable interrupts while drawing but usually
  211.           drawing takes up alot of time and having interrupts disabled
  212.           for too long is not a good idea.
  213.  
  214.   x_define_mouse_cursor
  215.   ---------------------
  216.  
  217.   C Prototype:
  218.     void x_define_mouse_cursor(char far *MouseDef, unsigned char MouseColor)
  219.  
  220.     MouseDef - a pointer to 14 characters containing a bitmask for all the
  221.            cursor's rows.
  222.     MouseColor - The colour to use when drawing the mouse cursor.
  223.  
  224.   Define a mouse cursor shape for use in subsequent cursor redraws. XMouse
  225.   has a hardwired mouse cursor size of 8 pixels across by 14 pixels down.
  226.  
  227.   WARNING: This function assumes MouseDef points to 14 bytes.
  228.  
  229.   Note: Bit order is in reverse. ie bit 7 represents pixel 0 ..
  230.     bit 0 represents pixel 7 in each "MouseDef" byte.
  231.  
  232.   x_show_mouse
  233.   ------------
  234.  
  235.   C Prototype:  void x_show_mouse()
  236.  
  237.   Makes the cursor visible if it was previously hidden.
  238.   See Also: "x_hide_mouse".
  239.  
  240.   x_hide_mouse
  241.   ------------
  242.  
  243.   C Prototype:  void x_hide_mouse()
  244.  
  245.   Makes the cursor hidden if it was previously visible.
  246.   See Also: "x_show_mouse".
  247.  
  248.   x_remove_mouse
  249.   --------------
  250.  
  251.   C Prototype:  void x_remove_mouse()
  252.  
  253.   Stop mouse event handling and remove the mouse handler.
  254.  
  255.   NOTE: This function MUST be called before quitting the program if
  256.        a mouse handler has been installed
  257.  
  258.   x_position_mouse
  259.   ----------------
  260.  
  261.   C Prototype  void x_position_mouse(int x, int y)
  262.  
  263.   Positions the mouse cursor at the specified location
  264.  
  265.   x_update_mouse
  266.   --------------
  267.  
  268.   C Prototype:  void x_update_mouse()
  269.  
  270.   Forces the mouse position to be updated and cursor to be redrawn.
  271.   Note: this function is useful when you have set "MouseFrozen" to true.
  272.   Allows the cursor position to be updated manually rather than
  273.   automatically by the installed handler.
  274.  
  275. --------------------------------------------------------------------------
  276. MODULE  XCIRCLE
  277. --------------------------------------------------------------------------
  278.                 XCIRCLE:
  279.               Wheel Have to See About That
  280.              by Matthew MacKenzie
  281.  
  282. The XCIRCLE module contains two functions, neither of which should be
  283. a big mystery:
  284.   o  x_circle, oddly enough, draws a circle.
  285.   o  x_filled_circle does too, only the circle is filled (in some
  286.      libraries this is called a disc).
  287.  
  288.     The word `circle' here refers to a round thing which is as many
  289. pixels tall as across.  It only looks like a circle in 320x240 mode --
  290. the original mode X -- and in 376x282 mode.
  291.     In both functions, the circle is specified by the coordinates of the
  292. upper-left-hand corner of the smallest box which holds it, and the
  293. diameter.  Some circle functions have you specify a center point;
  294. this system is kind of odd because a circle with an even diameter does
  295. not have a particular pixel for a center.  Every circle, on the other
  296. hand, has a box with an upper-left corner.
  297.     No bounds are checked.  A diameter of zero will draw nothing, and
  298. a negative diameter will blow your VGA board into hundreds of thousands
  299. of tiny little smoldering fragments.  Neither function supports clipping.
  300.     The calculation of the circle is based on an algorithm described
  301. by Michael P. Lindner in a letter to the editor on page 8 of Dr. Dobb's
  302. Journal #169 (October 1990).  The algorithm has been rearranged to
  303. allow drawing and moving the plots in the eight octants to be performed
  304. in one step, so that each pixel does not have to be loaded into the CPU
  305. twice.  x_filled_circle does not take advantage of this optimization
  306. because it handles different parts of each plot at different times.
  307.  
  308.   ASM SOURCES
  309.  
  310.   xcircle.asm xcircle.inc xlib.inc model.inc
  311.  
  312.   C HEADER FILE
  313.  
  314.   xcircle.h
  315.  
  316.   EXPORTED FUNCTIONS
  317.  
  318.   x_circle
  319.   --------
  320.   C Prototype: extern void x_circle (WORD Left, WORD Top, WORD Diameter,
  321.                      WORD Color, WORD ScreenOffs);
  322.  
  323.   Draws a circle with the given upper-left-hand corner and diameter,
  324.   which are given in pixels.
  325.  
  326.  
  327.   x_filled_circle
  328.   ---------------
  329.   C Prototype: extern void x_filled_circle (WORD Left, WORD Top,
  330.                 WORD Diameter, WORD Color, WORD ScreenOffs);
  331.  
  332.   Draws a filled circle with the given upper-left-hand corner and
  333.   diameter.
  334.  
  335.  
  336. --------------------------------------------------------------------------
  337. MODULE XDETECT
  338. --------------------------------------------------------------------------
  339.  
  340.   This module implements a set of functions to detect the PC's hardware
  341.   configuration.
  342.  
  343.   ASM SOURCES
  344.  
  345.     xdetect.asm xdetect.inc model.inc
  346.  
  347.   C HEADER FILE
  348.  
  349.     xdetect.h
  350.  
  351.   EXPORTED MACROS
  352.  
  353.     I8086   0
  354.     I80186  1
  355.     I80286  2
  356.     I80386  3
  357.  
  358.     NoGraphics 0
  359.     MDA        1
  360.     CGA        2
  361.     EGAMono    3
  362.     EGAColor   4
  363.     VGAMono    5
  364.     VGAColor   6
  365.     MCGAMono   7
  366.     MCGAColor  8
  367.  
  368.     BUS_MOUSE     1
  369.     SERIAL_MOUSE  2
  370.     INPORT_MOUSE  3
  371.     PS2_MOUSE     4
  372.     HP_MOUSE      5
  373.  
  374.  
  375.   EXPORT VARIABLES
  376.  
  377.   MouseButtonCount  - WORD - The number of buttons on the detected mouse
  378.   MouseVersion      - WORD - Mouse driver version (High byte = Major version
  379.                  Low byte = minor version)
  380.   MouseType         - BYTE - The mouse type
  381.   MouseIRQ          - BYTE - The IRQ number used by the mouse driver
  382.  
  383.   EXPORT FUNCTIONS
  384.  
  385.  
  386.   x_graphics_card
  387.   ---------------
  388.   C Prototype: extern int x_graphics_card();
  389.  
  390.   This function returns the type of graphics card installed. See defines
  391.   above.
  392.  
  393.   x_processor
  394.   -----------
  395.   C Prototype: extern int x_processor();
  396.  
  397.   This function returns the type of processor installed. A 486 registers
  398.   as a 386. See defines above.
  399.  
  400.   x_coprocessor
  401.   -------------
  402.   C Prototype: extern int x_coprocessor();
  403.  
  404.   This function returns 1 of a numeric co-processor is present, 0 if not.
  405.   The type is not detected but it's mnot really necessary as the processor
  406.   type usually determines the numeric coprocessor type
  407.  
  408.   x_mousedriver
  409.   -------------
  410.   C Prototype: extern int x_mousedriver();
  411.  
  412.   This function returns 1 of a mouse driver is installed, 0 otherwise.
  413.   If a mouse driver is detected the mouse related variable (above) are
  414.   set accordingly.
  415.  
  416. --------------------------------------------------------------------------
  417. MODULE XFILEIO
  418. --------------------------------------------------------------------------
  419.  
  420.   Handle based file I/O functions.
  421.  
  422.   See any good DOS programming reference for more information on int 21h
  423.   DOS services.
  424.  
  425.   ASM SOURCES
  426.  
  427.     xfileio.asm xfileio.inc model.inc
  428.  
  429.   C HEADER FILE
  430.  
  431.     xfileio.h
  432.  
  433.   EXPORTED MACROS
  434.  
  435.   file access modes
  436.  
  437.     F_RDONLY
  438.     F_WRONLY
  439.     F_RDWR
  440.  
  441.   seek codes
  442.  
  443.     SEEK_START
  444.     SEEK_CURR
  445.     SEEK_END
  446.  
  447.   file error value
  448.  
  449.     FILE_ERR
  450.  
  451.   EXPORT FUNCTIONS
  452.  
  453.   f_open
  454.   ------
  455.   C Prototype: extern int f_open(char * filename, char access);
  456.  
  457.   Opens a file according to the access char:
  458.  
  459.     F_RDONLY = read only   - If doesnt exist return error
  460.     F_WRONLY = write only  - If doesnt exist create it otherwise clear it
  461.     F_RDWR   = read/write  - If doesnt exist create it
  462.  
  463.   Returns the file handle on success, FILE_ERR on failure
  464.  
  465.  
  466.   f_close
  467.   -------
  468.  
  469.   C Prototype:  extern int f_close(int handle);
  470.  
  471.   Closes the file associated with the specified handle
  472.  
  473.   Returns 0 on success, FILE_ERR on failure
  474.  
  475.  
  476.   f_read
  477.   ------
  478.  
  479.   C Prototype:  extern int f_read(int handle, char far * buffer, int count);
  480.  
  481.   Reads a block of count bytes from the file specified by the handle
  482.   into the buffer
  483.  
  484.   Returns count on success, FILE_ERR on failure
  485.  
  486.  
  487.   f_write
  488.   -------
  489.  
  490.   C Prototype: extern int f_write(int handle, char far * buffer, int count);
  491.  
  492.   Writes a block of count bytes to the file specified by the handle
  493.   from the buffer
  494.  
  495.   Returns count on success, FILE_ERR on failure
  496.  
  497.  
  498.   f_seek
  499.   ------
  500.  
  501.   C Prototype: extern long int f_seek(int handle, long int position,
  502.                       char method_code)
  503.  
  504.   Moves the file pointer according to the position and method code
  505.  
  506.   Returns file pointer position on success, FILE_ERR on failure
  507.  
  508.  
  509.   f_filelength
  510.   ------------
  511.  
  512.   C Prototype:
  513.  
  514.     extern long int f_filelength(int handle)
  515.  
  516.   Returns the length of the file associated with the specified handle
  517.  
  518.   Returns file length on success, FILE_ERR on failure
  519.  
  520.  
  521. --------------------------------------------------------------------------
  522. MODULE XRLETOOL
  523. --------------------------------------------------------------------------
  524.  
  525. This module implements a number of functions comprising an RLE encoding
  526. decoding system.
  527.  
  528. RLE stands for RUN LENGTH ENCODING. It is a quick simple data compression
  529. scheme which is commonly used for image data compression or compression
  530. of any data. Although not the most efficient system, it is fast, which is
  531. why it is used in image storage systems like PCX. This implementation is
  532. more efficient than the one used in PCX files because it uses 1 bit to
  533. identify a Run Length byte as opposed to two in PCX files, but more on this
  534. later.
  535.  
  536. This set of functions can be used to implement your own compressed image
  537. file format or for example compress game mapse for various levels etc.
  538. The uses are limited by your imagination.
  539.  
  540. I opted for trading off PCX RLE compatibility for the improved compression
  541. efficiency.
  542.  
  543. Here is how the data is un-compressed to give an idea of its structure.
  544.  
  545.  
  546. STEP 1 read a byte from the RLE compressed source buffer.
  547.  
  548. STEP 2 if has its high bit is set then the lower 7 bits represent the number
  549.        of times the next byte is to be repeated in the destination buffer.
  550.        if the count (lower 7 bits) is zero then
  551.       we have finished decoding goto STEP 5
  552.        else goto STEP 4
  553.  
  554. STEP 3 Read a data from the source buffer and copy it directly to the
  555.        destination buffer.
  556.        goto STEP 1
  557.  
  558. STEP 4 Read a data byte from the source buffer and copy it to the destination
  559.        buffer the number of times specified by step 2.
  560.        goto STEP 1
  561.  
  562. STEP 5 Stop, decoding done.
  563.  
  564. If the byte does not have the high bit set then the byte itself is transfered
  565.  to the destination buffer.
  566.  
  567. Data bytes that have the high bit already set and are unique in the input
  568.  stream are represented as a Run Length of 1 (ie 81 which includes high bit)
  569.  followed by the data byte.
  570.  
  571. If your original uncompressed data contains few consecutive bytes and most
  572. have high bit set (ie have values > 127) then your so called
  573. compressed data would require up to 2x the space of the uncompressed data,
  574. so be aware that the compression ratio is extremely variable depending on the
  575. type of data being compressed.
  576.  
  577. Apologies for this poor attempt at a description, but you can look up
  578. RLE in any good text. Alternatively, any text that describes the PCX file
  579. structure in any depth should have a section on RLE compression.
  580.  
  581.  
  582.  
  583.   ASM SOURCES
  584.  
  585.     xrletool.asm xrletool.inc model.inc
  586.  
  587.   C HEADER FILE
  588.  
  589.     xrletool.h
  590.  
  591.   EXPORTED MACROS
  592.  
  593.  
  594.   EXPORT FUNCTIONS
  595.  
  596.   x_buff_RLDecode
  597.   ---------------
  598.  
  599.    Expands an RLE compresses source buffer to a destination buffer.
  600.    returns the size of the resultant uncompressed data.
  601.  
  602.    C PROTOTYPE:
  603.  
  604.    extern unsigned int x_buff_RLDecode(char far * source_buff,
  605.                       char far * dest_buff);
  606.  
  607.    source_buff   - The buffer to compress
  608.    dest_buff     - The destination buffer
  609.  
  610.    WARNING: buffers must be pre allocated.
  611.  
  612.  
  613.    x_buff_RLEncode
  614.    ---------------
  615.  
  616.    RLE Compresses a source buffer to a destination buffer and returns
  617.    the size of the resultant compressed data.
  618.  
  619.    C PROTOTYPE:
  620.  
  621.     extern unsigned int x_buff_RLEncode(char far * source_buff,
  622.          char far * dest_buff,unsigned int count);
  623.  
  624.    source_buff   - The buffer to compress
  625.    dest_buff     - The destination buffer
  626.    count         - The size of the source data in bytes
  627.  
  628.    WARNING: buffers must be pre allocated.
  629.  
  630.    x_buff_RLE_size
  631.    ---------------
  632.  
  633.    Returns the size the input data would compress to.
  634.  
  635.    C PROTOTYPE:
  636.  
  637.     extern unsigned int x_buff_RLE_size(char far * source_buff,
  638.          unsigned int count);
  639.  
  640.    source_buff   - The uncompressed data buffer
  641.    count         - The size of the source data in bytes
  642.  
  643.  
  644.    x_file_RLEncode
  645.    ---------------
  646.  
  647.    RLE Compresses a source buffer to an output file returning
  648.    the size of the resultant compressed data or 0 if it fails.
  649.  
  650.    C PROTOTYPE:
  651.  
  652.    extern unsigned int x_file_RLEncode(int handle,
  653.      char far * source_buff,unsigned int count);
  654.  
  655.    source_buff   - The buffer to compress
  656.    handle        - The file handler
  657.    count         - The size of the source data in bytes
  658.  
  659.    x_file_RLDecode
  660.    ---------------
  661.  
  662.    Expands an RLE compresses file to a destination RAM buffer.
  663.    returns the size of the resultant uncompressed data.
  664.  
  665.    C PROTOTYPE:
  666.  
  667.     extern unsigned int x_buff_RLDecode(int handle,
  668.          char far * dest_buff);
  669.  
  670.    handle        - Input file handle
  671.    dest_buff     - The destination buffer
  672.  
  673. --------------------------------------------------------------------
  674. REFERENCE SECTION
  675. --------------------------------------------------------------------
  676.  
  677.  
  678. REFERENCES
  679. ----------
  680.  
  681. In my opinion Doctor Dobbs Journal is the best reference text for
  682. VGA Mode X graphics:
  683.  
  684. Issue 178 Jul 1991 : First reference to Mode X
  685. Article Abstract   : VGA's undocumented Mode X supports page flipping,
  686.              makes off screen memory available, has square pixels,
  687.              and increases performance by as muck as 4 times.
  688.  
  689. Issue 179 Aug 1991 : Continuation
  690. Article Abstract   : Michael discusses latches and VGA's undoccumented
  691.              Mode X.
  692.  
  693. Issue 181 Sep 1991 : Continuation
  694. Article Abstract   : Michael puts the moves on animation using VGA's 256
  695.              colors.
  696.  
  697. Issue 184 Oct 1991 : First of a continuing series covering 3-D animation
  698.              using VGA's Mode X. This series is still ongoing
  699.              (October 1992)
  700. Article Abstract   : Michael moves into 3-D animation, starting with basic
  701.              polygon fills and page flips.
  702.  
  703.  
  704. WHAT IS MODE X ?
  705. ----------------
  706.  
  707. Mode X is a derrivative of the VGA's standard mode 13h (320x200 256 color).
  708. It is a (family) of undocumented video modes that are created by tweaking
  709. the VGA's registers. The beauty of mode X is that it offers several
  710. benefits to the programmer:
  711.  - Multiple graphice pages where mode 13h doesn't allowing for page flipping
  712.    (also known as double buffering) and storage of images and data in
  713.    offscreen video memory
  714.  - A planar video ram organization which although more difficult to program,
  715.    allows the VGA's plane-oriented hardware to be used to process pixels in
  716.    parallel, improving performance by up to 4 times over mode 13h
  717.  
  718.    See issue 178-179 of D.D.J. for a full description of VGA's Mode X.
  719.  
  720. WHAT IS A SPLIT SCREEN ?
  721. ------------------------
  722.  
  723. A split screen is a neat hardware feature offered by the EGA and VGA video
  724. cards. A split screen is a mode of graphics operationin which the Hardware
  725. splits the visual graphics screen horizontally and treats both halves as
  726. individual screens each starting at different locations in video RAM.
  727.  
  728. The bottom half (which is usually referred to as the split screen) always
  729. starts at address A000:0000 but the top half's starting address is user
  730. definable.
  731.  
  732. The most common application of split screens in games is the status display
  733. in scrolling games. Split screens make this sort of game simpler to program
  734. because when the top half window is scrolled the programmer does not have to
  735. worry about redrawing the bottom half.
  736.  
  737. WHAT IS DOUBLE BUFFERING ?
  738. --------------------------
  739.  
  740. Double buffering (also known as page flipping) is the technique most often
  741. used to do animation. it requires hardware that is capable of displaying
  742. multiple graphics pages (or at least 2). Animation is achieved by drawing
  743. an image in the non visible screen and then displaying the non visible
  744. screen. Once the page has been flipped the process starts again. The next
  745. frame of the animation is drawn on the non visible screen, the page is
  746. flipped again etc.
  747.  
  748. WHAT IS MODE X ?
  749. ----------------
  750.  
  751. Mode X is a derrivative of the VGA's standard mode 13h (320x200 256 color).
  752. It is a (family) of undocumented video modes that are created by tweaking
  753. the VGA's registers. The beauty of mode X is that it offers several
  754. benefits to the programmer:
  755.  - Multiple graphice pages where mode 13h doesn't allowing for page flipping
  756.    (also known as double buffering) and storage of images and data in
  757.    offscreen video memory
  758.  - A planar video ram organization which although more difficult to program,
  759.    allows the VGA's plane-oriented hardware to be used to process pixels in
  760.    parallel, improving performance by up to 4 times over mode 13h
  761.  
  762.    Again see D.D.J. for an in depth discussion of animation using Mode X.
  763.  
  764.    -----------------------------------------------------------------------
  765.  
  766.  
  767.